<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        
        <meta name="author" content="MkDocs Team">
        <link rel="canonical" href="https://www.mkdocs.org/user-guide/customizing-your-theme/">
        <link rel="shortcut icon" href="../../img/favicon.ico">
        <title>Customizing Your Theme - MkDocs</title>
        <link href="../../css/bootstrap.min.css" rel="stylesheet">
        <link href="../../css/font-awesome.min.css" rel="stylesheet">
        <link href="../../css/base.css" rel="stylesheet">
        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css">
        <link href="../../css/extra.css" rel="stylesheet">

        <script src="../../js/jquery-1.10.2.min.js" defer></script>
        <script src="../../js/bootstrap.min.js" defer></script>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/languages/yaml.min.js"></script>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/languages/django.min.js"></script>
        <script>hljs.initHighlightingOnLoad();</script>
        <script async src="https://www.googletagmanager.com/gtag/js?id=G-274394082"></script>
        <script>
          window.dataLayer = window.dataLayer || [];
          function gtag(){dataLayer.push(arguments);}
          gtag('js', new Date());

          gtag('config', 'G-274394082');
        </script> 
    </head>

    <body>
        <div class="navbar fixed-top navbar-expand-lg navbar-dark bg-primary">
            <div class="container">
                <a class="navbar-brand" href="../..">MkDocs</a>
                <!-- Expander button -->
                <button type="button" class="navbar-toggler" data-toggle="collapse" data-target="#navbar-collapse">
                    <span class="navbar-toggler-icon"></span>
                </button>

                <!-- Expanded navigation -->
                <div id="navbar-collapse" class="navbar-collapse collapse">
                        <!-- Main navigation -->
                        <ul class="nav navbar-nav">
                            <li class="navitem">
                                <a href="../.." class="nav-link">Home</a>
                            </li>
                            <li class="navitem">
                                <a href="../../getting-started/" class="nav-link">Getting Started</a>
                            </li>
                            <li class="dropdown active">
                                <a href="#" class="nav-link dropdown-toggle" data-toggle="dropdown">User Guide <b class="caret"></b></a>
                                <ul class="dropdown-menu">
                                    
<li>
    <a href="../" class="dropdown-item">Overview</a>
</li>
                                    
<li>
    <a href="../installation/" class="dropdown-item">Installation</a>
</li>
                                    
<li>
    <a href="../writing-your-docs/" class="dropdown-item">Writing Your Docs</a>
</li>
                                    
<li>
    <a href="../choosing-your-theme/" class="dropdown-item">Choosing Your Theme</a>
</li>
                                    
<li>
    <a href="./" class="dropdown-item active">Customizing Your Theme</a>
</li>
                                    
<li>
    <a href="../localizing-your-theme/" class="dropdown-item">Localizing Your Theme</a>
</li>
                                    
<li>
    <a href="../configuration/" class="dropdown-item">Configuration</a>
</li>
                                    
<li>
    <a href="../deploying-your-docs/" class="dropdown-item">Deploying Your Docs</a>
</li>
                                </ul>
                            </li>
                            <li class="dropdown">
                                <a href="#" class="nav-link dropdown-toggle" data-toggle="dropdown">Developer Guide <b class="caret"></b></a>
                                <ul class="dropdown-menu">
                                    
<li>
    <a href="../../dev-guide/" class="dropdown-item">Overview</a>
</li>
                                    
<li>
    <a href="../../dev-guide/themes/" class="dropdown-item">Themes</a>
</li>
                                    
<li>
    <a href="../../dev-guide/translations/" class="dropdown-item">Translations</a>
</li>
                                    
<li>
    <a href="../../dev-guide/plugins/" class="dropdown-item">Plugins</a>
</li>
                                </ul>
                            </li>
                            <li class="dropdown">
                                <a href="#" class="nav-link dropdown-toggle" data-toggle="dropdown">About <b class="caret"></b></a>
                                <ul class="dropdown-menu">
                                    
<li>
    <a href="../../about/release-notes/" class="dropdown-item">Release Notes</a>
</li>
                                    
<li>
    <a href="../../about/contributing/" class="dropdown-item">Contributing</a>
</li>
                                    
<li>
    <a href="../../about/license/" class="dropdown-item">License</a>
</li>
                                </ul>
                            </li>
                        </ul>

                    <ul class="nav navbar-nav ml-auto">
                        <li class="nav-item">
                            <a href="#" class="nav-link" data-toggle="modal" data-target="#mkdocs_search_modal">
                                <i class="fa fa-search"></i> Search
                            </a>
                        </li>
                            <li class="nav-item">
                                <a rel="prev" href="../choosing-your-theme/" class="nav-link">
                                    <i class="fa fa-arrow-left"></i> Previous
                                </a>
                            </li>
                            <li class="nav-item">
                                <a rel="next" href="../localizing-your-theme/" class="nav-link">
                                    Next <i class="fa fa-arrow-right"></i>
                                </a>
                            </li>
                            <li class="nav-item">
                                <a href="https://gitee.com/fstongxue/aivideo.git" class="nav-link">Gitee</a>
                            </li>
                    </ul>
                </div>
            </div>
        </div>

        <div class="container">
            <div class="row">
                    <div class="col-md-3"><div class="navbar-light navbar-expand-md bs-sidebar hidden-print affix" role="complementary">
    <div class="navbar-header">
        <button type="button" class="navbar-toggler collapsed" data-toggle="collapse" data-target="#toc-collapse" title="Table of Contents">
            <span class="fa fa-angle-down"></span>
        </button>
    </div>

    
    <div id="toc-collapse" class="navbar-collapse collapse card bg-secondary">
        <ul class="nav flex-column">
            
            <li class="nav-item" data-level="1"><a href="#customizing-your-theme" class="nav-link">Customizing Your Theme</a>
              <ul class="nav flex-column">
            <li class="nav-item" data-level="2"><a href="#using-the-docs_dir" class="nav-link">Using the docs_dir</a>
              <ul class="nav flex-column">
              </ul>
            </li>
            <li class="nav-item" data-level="2"><a href="#using-the-theme-custom_dir" class="nav-link">Using the theme custom_dir</a>
              <ul class="nav flex-column">
              </ul>
            </li>
              </ul>
            </li>
        </ul>
    </div>
</div></div>
                    <div class="col-md-9" role="main">

<h1 id="customizing-your-theme">Customizing Your Theme<a class="headerlink" href="#customizing-your-theme" title="Permanent link"></a></h1>
<p>Altering a theme to suit your needs.</p>
<hr />
<p>If you would like to make a few tweaks to an existing theme, there is no need
to create your own theme from scratch. For minor tweaks which only require
some CSS and/or JavaScript, you can <a href="#using-the-docs_dir">use the docs_dir</a>.
However, for more complex customizations, including overriding templates, you
will need to <a href="#using-the-theme-custom_dir">use the theme custom_dir</a> setting.</p>
<h2 id="using-the-docs_dir">Using the docs_dir<a class="headerlink" href="#using-the-docs_dir" title="Permanent link"></a></h2>
<p>The <a href="../configuration/#extra_css">extra_css</a> and <a href="../configuration/#extra_javascript">extra_javascript</a> configuration options can be used to
make tweaks and customizations to existing themes. To use these, you simply
need to include either CSS or JavaScript files within your <a href="../configuration/#docs_dir">documentation
directory</a>.</p>
<p>For example, to change the color of the headers in your documentation, create
a file called <code>extra.css</code> and place it next to the documentation Markdown. In
that file add the following CSS.</p>
<pre><code class="language-CSS">h1 {
  color: red;
}
</code></pre>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If you are deploying your documentation with <a href="../deploying-your-docs/#readthedocs">ReadTheDocs</a>. You will need
to explicitly list the CSS and JavaScript files you want to include in
your config. To do this, add the following to your mkdocs.yml.</p>
<pre><code>extra_css: [extra.css]
</code></pre>
</div>
<p>After making these changes, they should be visible when you run
<code>mkdocs serve</code> - if you already had this running, you should see that the CSS
changes were automatically picked up and the documentation will be updated.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Any extra CSS or JavaScript files will be added to the generated HTML
document after the page content. If you desire to include a JavaScript
library, you may have better success including the library by using the
theme <a href="../configuration/#custom_dir">custom_dir</a>.</p>
</div>
<h2 id="using-the-theme-custom_dir">Using the theme custom_dir<a class="headerlink" href="#using-the-theme-custom_dir" title="Permanent link"></a></h2>
<p>The <a href="../configuration/#custom_dir"><code>theme.custom_dir</code></a> configuration option can be used to point
to a directory of files which override the files in a parent theme. The parent
theme would be the theme defined in the <a href="../configuration/#name"><code>theme.name</code></a> configuration
option. Any file in the <code>custom_dir</code> with the same name as a file in the
parent theme will replace the file of the same name in the parent theme. Any
additional files in the <code>custom_dir</code> will be added to the parent theme. The
contents of the <code>custom_dir</code> should mirror the directory structure of the
parent theme. You may include templates, JavaScript files, CSS files, images,
fonts, or any other media included in a theme.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>For this to work, the <code>theme.name</code> setting must be set to a known
installed theme. If the <code>name</code> setting is instead set to <code>null</code> (or not
defined), then there is no theme to override and the contents of the
<code>custom_dir</code> must be a complete, standalone theme. See the <a href="../../dev-guide/themes/">Theme
Developer Guide</a> for more information.</p>
</div>
<p>For example, the <a href="../choosing-your-theme/#mkdocs">mkdocs</a> theme (<a href="https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes/mkdocs">browse source</a>), contains the following
directory structure (in part):</p>
<pre><code class="language-nohighlight">- css\
- fonts\
- img\
  - favicon.ico
  - grid.png
- js\
- 404.html
- base.html
- content.html
- nav-sub.html
- nav.html
- toc.html
</code></pre>
<p>To override any of the files contained in that theme, create a new directory
next to your <code>docs_dir</code>:</p>
<pre><code class="language-bash">mkdir custom_theme
</code></pre>
<p>And then point your <code>mkdocs.yml</code> configuration file at the new directory:</p>
<pre><code class="language-yaml">theme:
    name: mkdocs
    custom_dir: custom_theme/
</code></pre>
<p>To override the 404 error page ("file not found"), add a new template file named
<code>404.html</code> to the <code>custom_theme</code> directory. For information on what can be
included in a template, review the <a href="../../dev-guide/themes/">Theme Developer Guide</a>.</p>
<p>To override the favicon, you can add a new icon file at
<code>custom_theme/img/favicon.ico</code>.</p>
<p>To include a JavaScript library, copy the library to the <code>custom_theme/js/</code>
directory.</p>
<p>Your directory structure should now look like this:</p>
<pre><code class="language-nohighlight">- docs/
  - index.html
- custom_theme/
  - img/
    - favicon.ico
  - js/
    - somelib.js
  - 404.html
- config.yml
</code></pre>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Any files included in the parent theme (defined in <code>name</code>) but not
included in the <code>custom_dir</code> will still be utilized. The <code>custom_dir</code> will
only override/replace files in the parent theme. If you want to remove
files, or build a theme from scratch, then you should review the <a href="../../dev-guide/themes/">Theme
Developer Guide</a>.</p>
</div>
<h3 id="overriding-template-blocks">Overriding Template Blocks<a class="headerlink" href="#overriding-template-blocks" title="Permanent link"></a></h3>
<p>The built-in themes implement many of their parts inside template blocks which
can be individually overridden in the <code>main.html</code> template. Simply create a
<code>main.html</code> template file in your <code>custom_dir</code> and define replacement blocks
within that file. Just make sure that the <code>main.html</code> extends <code>base.html</code>. For
example, to alter the title of the MkDocs theme, your replacement <code>main.html</code>
template would contain the following:</p>
<pre><code class="language-django">{% extends &quot;base.html&quot; %}

{% block htmltitle %}
&lt;title&gt;Custom title goes here&lt;/title&gt;
{% endblock %}
</code></pre>
<p>In the above example, the <code>htmltitle</code> block defined in your custom <code>main.html</code> file
will be used in place of the default <code>htmltitle</code> block defined in the parent theme.
You may re-define as many blocks as you desire, as long as those blocks are
defined in the parent. For example, you could replace the Google Analytics
script with one for a different service or replace the search feature with your
own. You will need to consult the parent theme you are using to determine what
blocks are available to override. The MkDocs and ReadTheDocs themes provide the
following blocks:</p>
<ul>
<li><code>site_meta</code>: Contains meta tags in the document head.</li>
<li><code>htmltitle</code>: Contains the page title in the document head.</li>
<li><code>styles</code>: Contains the link tags for stylesheets.</li>
<li><code>libs</code>: Contains the JavaScript libraries (jQuery, etc) included in the page header.</li>
<li><code>scripts</code>: Contains JavaScript scripts which should execute after a page loads.</li>
<li><code>analytics</code>: Contains the analytics script.</li>
<li><code>extrahead</code>: An empty block in the <code>&lt;head&gt;</code> to insert custom tags/scripts/etc.</li>
<li><code>site_name</code>: Contains the site name in the navigation bar.</li>
<li><code>site_nav</code>: Contains the site navigation in the navigation bar.</li>
<li><code>search_button</code>: Contains the search box in the navigation bar.</li>
<li><code>next_prev</code>: Contains the next and previous buttons in the navigation bar.</li>
<li><code>repo</code>: Contains the repository link in the navigation bar.</li>
<li><code>content</code>: Contains the page content and table of contents for the page.</li>
<li><code>footer</code>: Contains the page footer.</li>
</ul>
<p>You may need to view the source template files to ensure your modifications will
work with the structure of the site. See <a href="../../dev-guide/themes/#template-variables">Template Variables</a> for a list of
variables you can use within your custom blocks. For a more complete
explanation of blocks, consult the <a href="http://jinja.pocoo.org/docs/dev/templates/#template-inheritance">Jinja documentation</a>.</p>
<h3 id="combining-the-custom_dir-and-template-blocks">Combining the custom_dir and Template Blocks<a class="headerlink" href="#combining-the-custom_dir-and-template-blocks" title="Permanent link"></a></h3>
<p>Adding a JavaScript library to the <code>custom_dir</code> will make it available, but
won't include it in the pages generated by MkDocs. Therefore, a link needs to
be added to the library from the HTML.</p>
<p>Starting the with directory structure above (truncated):</p>
<pre><code class="language-nohighlight">- docs/
- custom_theme/
  - js/
    - somelib.js
- config.yml
</code></pre>
<p>A link to the <code>custom_theme/js/somelib.js</code> file needs to be added to the
template. As <code>somelib.js</code> is a JavaScript library, it would logically go in the
<code>libs</code> block. However, a new <code>libs</code> block that only includes the new script will
replace the block defined in the parent template and any links to libraries in
the parent template will be removed. To avoid breaking the template, a
<a href="http://jinja.pocoo.org/docs/dev/templates/#super-blocks">super block</a> can be used with a call to <code>super</code> from within the block:</p>
<pre><code class="language-django">{% extends &quot;base.html&quot; %}

{% block libs %}
    {{ super() }}
    &lt;script src=&quot;{{ base_url }}/js/somelib.js&quot;&gt;&lt;/script&gt;
{% endblock %}
</code></pre>
<p>Note that the <a href="../../dev-guide/themes/#base_url">base_url</a> template variable was used to ensure that the link is
always relative to the current page.</p>
<p>Now the generated pages will include links to the template provided libraries as
well as the library included in the <code>custom_dir</code>. The same would be required for
any additional CSS files included in the <code>custom_dir</code>.</p></div>
            </div>
        </div>

        <footer class="col-md-12">
            <hr>
                <p>Copyright &copy; 2014 <a href="https://twitter.com/_tomchristie">Tom Christie</a>, Maintained by the <a href="/about/release-notes/#maintenance-team">MkDocs Team</a>.</p>
            <p>Documentation built with <a href="https://www.mkdocs.org/">MkDocs</a>.</p>
        </footer>
        <script>
            var base_url = "../..",
                shortcuts = {"help": 191, "next": 78, "previous": 80, "search": 83};
        </script>
        <script src="../../js/base.js" defer></script>
        <script src="../../search/main.js" defer></script>

        <div class="modal" id="mkdocs_search_modal" tabindex="-1" role="dialog" aria-labelledby="searchModalLabel" aria-hidden="true">
    <div class="modal-dialog modal-lg">
        <div class="modal-content">
            <div class="modal-header">
                <h4 class="modal-title" id="searchModalLabel">Search</h4>
                <button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">&times;</span><span class="sr-only">Close</span></button>
            </div>
            <div class="modal-body">
                <p>From here you can search these documents. Enter your search terms below.</p>
                <form>
                    <div class="form-group">
                        <input type="search" class="form-control" placeholder="Search..." id="mkdocs-search-query" title="Type search term here">
                    </div>
                </form>
                <div id="mkdocs-search-results" data-no-results-text="No results found"></div>
            </div>
            <div class="modal-footer">
            </div>
        </div>
    </div>
</div><div class="modal" id="mkdocs_keyboard_modal" tabindex="-1" role="dialog" aria-labelledby="keyboardModalLabel" aria-hidden="true">
    <div class="modal-dialog">
        <div class="modal-content">
            <div class="modal-header">
                <h4 class="modal-title" id="keyboardModalLabel">Keyboard Shortcuts</h4>
                <button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">&times;</span><span class="sr-only">Close</span></button>
            </div>
            <div class="modal-body">
              <table class="table">
                <thead>
                  <tr>
                    <th style="width: 20%;">Keys</th>
                    <th>Action</th>
                  </tr>
                </thead>
                <tbody>
                  <tr>
                    <td class="help shortcut"><kbd>?</kbd></td>
                    <td>Open this help</td>
                  </tr>
                  <tr>
                    <td class="next shortcut"><kbd>n</kbd></td>
                    <td>Next page</td>
                  </tr>
                  <tr>
                    <td class="prev shortcut"><kbd>p</kbd></td>
                    <td>Previous page</td>
                  </tr>
                  <tr>
                    <td class="search shortcut"><kbd>s</kbd></td>
                    <td>Search</td>
                  </tr>
                </tbody>
              </table>
            </div>
            <div class="modal-footer">
            </div>
        </div>
    </div>
</div>

    </body>
</html>
